So far we have dealt only with simple specifiers. These specifiers have been formName, formAbsolutePosition and formPropertyID.
Now it's time to get onto the complex specifiers. These are formRelativePosition, formTest, formRange and formWhose. Luckily the Object Support Library will handle the formWhose for you aslong as you install a compare procedure and a count procedure with the routine AESetObjectCallbacks(), these routines are needed by formTest anyway. More on that later, first we'll get formRelativePosition and formRange out of the way.
formRelativeForm Example
7Edit does not implement formRelativeForm for all text types, only cInsertionPoint. Feel free to implement cWord, cParagraph etc.
tell application "7Edit"
make new text at insertion point before first word ¬
of document 1 with data "Start Here"
end tell
We have seen how OSL and our code resolves up to the formRelativeForm specifier. In this case we'll get a TextToken descriptor for 'first word of document 1'. On further resolution TextElemFromTextAccessor() calls TextFormRelativePosition() with the typeMyText descriptor.
err = errAEWrongDataType; // Could do cChar, cWord… but
} // this is only a sample
if (noErr != err) goto done;
err = AECreateDesc(typeMyText, (Ptr)&aTextToken,
sizeof(aTextToken), result);
done:
return(err);
}
The routine then creates a token of zero length (for an insertion point) at either end of the token depending on the type of formRelative position. Admittedly the other types of text such as cWord and cParagraph would be a little more tricky. If you want to do it have a look at some of the routines GetTextTokenObjectSpecifier() uses in 'SVAETextUtils.c'. Not only will you get a greater understanding of creating object specifiers, you'll also find some routines that would be fairly useful.
formRange Example
Handling formRange is not too complicated in 7Edit. Consider the following script:
tell application "7Edit"
select text from character 12 thru character 18 ¬
of document "Untitled"
end tell
The object specifier for 'text from character 12 thru character 18 of document "Untitled"' can be diagramatically presented in the way below.
When we resolve this through the TextElemFromTextAccessor() the document is coerced to a TextToken descriptor as we've seen before. The routine TextFormRange() is then called through the switch statement.
The routine takes the two range descriptors which are of formAbsolutePosition, and resolves them into an internal representation i.e. TextToken's. It then creates a TextToken which begins at the starting token and goes to the end of the ending token.
formTest Example
As stated before, you need to install a compare procedure and a count procedure to support formTest. This is well worth doing as it makes your application much more powerful in scripting terms. In the sample code we install these procdures in the InstallObjectCallbacks() routine which is in 'SVAECompare.c'.
Here is an example script that uses these installed procedures:
tell application "7Edit"
delete every word of document 1 whose length > 5
end tell
The first thing that the OSL does in this script is to resolve 'document 1'. As we've seen before this gives us a WindowToken descriptor. The OSL then calls the count procedure to count all the words in a container which is our WindowToken descriptor.
We can see that the MyCountProc() then switches on the desired class to count, which in our case is cWord. Here our WindowToken descriptor gets coerced into a TextToken descriptor and the words in this are counted.
The OSL then goes through each word by creating a formAbsolutePosition object specifier for each and passing this along with a descriptor of the comparator and the operator to compare to our compare procedure.
ExtractData() resolves any object specifiers then uses HandleGetData(), which we saw before in the Get Data Example, to get a descriptor of the actual value. If the descriptor isn't of one of our token types then we assume that it's already a descriptor of an actual value. This will be the case for the comparison descriptor in our example. It will be a descriptor holding an integer of value 5.
The OSL creates a list and adds the formAbsolutePosition object specifier of every word that MyCompareProcedure() returns true to. This list forms the result for our example script.
Recording
One of the useful things about AppleScript is the ability to record your actions. Applications like Script Editor can record the actions of your application by intercepting all the Apple Events sent to your application. This means that things like Cut and Paste from the Edit menu need to cause an Apple Event to be sent. These events need to be of a similar form to what AppleScript would send your application. This involves creating object specifiers for elements affected.
Another example, let's go through what happens when we select Cut from the Edit menu.
Cut is handled by the DoCommand() routine in 'SVEditMain.c'. This calls a routine in 'SVAERecording.c' called IssueCutCommand().
SendSelectionEvent() gets an object specifier for the current selection and sticks this into a select event and sends it to itself. DoEditCommand() then creates a cut event and also sends it to itself.
Drag Manager Support
Most of the code that deals with the Drag Manager is in 'SVDrag.c'. Although Gestalt is used to check if the Drag Manager is available, a number of situations can occur that may cause the DragLib shared library to fail to load. Because we're weak linking to the library, we need to check we really have a connection to the shared library. This can be done quite simply by checking any symbol against the constant kUnresolvedSymbolAddress. The following code snippet shown this, and is done after Gestalt has been used in the CheckEnvironment routine.
So what can cause a shared library to fail to link? Well, the most common cause is a low memory situation. Even if the code is already loaded, a shared library may still allocate a new copy of its global data section.
Everything else is fairly well known, but I'll point out a few things just in case. It's important to draw a caret at the insertion point when tracking a drag operation which includes text. It can be very confusing for the user if this is not implemented. Also, intelligent Cut and Paste applies equally well to drag and drop operation. Quite simply, this involves handling the spaces at each end of a text selection. See “Inside Macintosh: More Macintosh Toolbox”, Chapter 2 “Scrap Manager”, Page 10 “Intelligent Cut and Paste” for more information. Something to watch out for is dropping text on the original selection. This can be easily overlooked, and usually results in an unpleasant user experience. You should not draw a caret over the original selection, and zoom the dragged text back to the selection if a drop occurs. Lastly, don't forget to delete the text selection if it's dragged to the Finder's Trash.
QuickDraw GX Printing Support
What it does
-Initializes and disposes the GX Managers
-Modifies and handles changes to the file menu
-Adds a gxJob to a 7Edit document
-Loads and saves a flattened version of the gxJob to a file
-Implements GX page setup and Print dialogs
-Implements GX print loop
It achieves much of the above by using the techniques described in the article "Adding QuickDraw GX Printing to QuickDraw Applications" by Dave Hersey (see Develop #19). I'd suggest you have a read of this to get the full story.
In addition, it shows how to:
-Duplicate a styled text edit record
-Print a styled text edit record
-Pass job information to windows using Apple Events
It's not intended to be a definitive 'document' on how to implement these features, but illustrates one way of doing it. Most of the code for the GX printing is in the file 'SVEditGXPrinting.c'.
How the interesting stuff works
Duplicating a styled text edit record
This is done by "DuplicateStyleTERec":
void DuplicateStyleTERec( TEHandle hSourceTE,
TEHandle *hDestTE,
Rect *destRect,
GrafPtr destPort )
hSourceTE Handle to a TERec which contains the text edit you want to copy.
hDestTE Handle returned containing the duplicated TERec.
destRect Rect which is used for the duplicates view and dest Rects.
destPort The port that the duplicated text edit will be in. The reason a port is passed is that you may wish to put the text edit in a different window.
First we set up the port to "destPort", then we use "TEStyleNew" to create a new styled TERec.
GetPort(&oldPort);
SetPort(destPort);
*hDestTE = TEStyleNew(destRect, destRect);
Next we must preserve the selected range of the source text edit record and the set the range selection range to include the entirety of the text.
oldSelStart = (*hSourceTE)->selStart;
oldSelEnd = (*hSourceTE)->selEnd;
TESetSelect(0,(*hSourceTE)->teLength, hSourceTE);
Now we can use "GetStylScrap" to get the style of the current selection - which is now the whole text. This being done we can reset the selection range.
printerTextStyles = GetStylScrap(hSourceTE);
TESetSelect(oldSelStart, oldSelEnd, hSourceTE);
"TEStyleInsert" is used to insert the text and acquired style from the source into the destination text edit (remembering to lock the source's text before trying to insert it).
HLock((Handle)((*hSourceTE)->hText));
TEStyleInsert ( (Ptr)*((*hSourceTE)->hText),
(*hSourceTE)->teLength,
printerTextStyles,
*hDestTE);
HUnlock((Handle)((*hSourceTE)->hText));
How to print a styled text edit record with QuickDraw GX
This is done in the function "GXPrintLoop". It uses a modified version of the print loop from Develop 19. It creates a invisible window to draw the text edit record into. This is because "TEUpdate" is used to do the drawing and it will not only draw into the printer port, but will also draw in it's own port. Therefore we need to create an 'invisible' port to draw into. So we give the window an empty (0,0,0,0) rect for bounds and we set the visible flag to false.
Now we duplicate the Text Edit record in the document, to a temporary record. Then we use "GetPageEnds" to calculate how many pages are needed and where each page ends.
Next it puts up the progress dialog then it steps through the pages. At each page, it clips the text edit rec so it only draw lines of text on the page. It then uses TEUpdate to draw each page.
Once we've printed all the pages we finish the job and dispose of any structures we've created.
How to pass job information to windows using Apple Events
The GX printing code passes the job to and from the window using the Set/GetWindowProperty functions. It declares a new token property:
#define pGXPageSetup 'TFGX'
The GXJob is then passed in a flattened state using "GXFlattenJobToHdl()" to flatten it down to a handle, or "GXUnflattenJobFromHdl()" to extract it again.
7Edit Background and Changes
7Edit was originally written when the Object Support Library was still in it's early stages. This update hopefully makes the flow of events easier to follow, even if this means not doing things in the most clever way. Each Apple Event handler is now in it's own file, except for those in the Required Suite which are still in 'SVAppleEvents.c'. So if you want to look at the delete handler look in 'SVAEDelete.c'. The accessor routines have been moved into the 'SVAEAccessors.c' file and the coercion routines to 'SVAECoercions.c'. Alot of the extra routines that help the event handlers deal with windows and text have been moved to 'SVAEWindowUtils.c' and 'SVAETextUtils.c' respectively.
Support for the Edition Manager has been taken out. The code had some bugs in it, and wasn't a major part of 7Edit. However, 7Edit now includes support for QuickDraw GX printing and the Drag Manager.
We also removed and added items to make 7Edit closer to the Scriptable Text Editor. This included the line class which is in the Text Suite.
AppleEvents and C++
If you are thinking of writing a scriptable application it may be worth your while looking at Metrowerk's PowerPlant and the latest version of MacApp 3.3. Both of these frameworks support scripting.
Known Problems
You may find that your machine will crash if you don't have a printer selected through the Chooser.
Further Things That Could Be Done
• Even though 7Edit supports drag and drop it is as yet unrecordable. This requires some thought because it has to be to handle dragging to and from other applications, including the Finder.
• The Scriptable Text Editor allows you to specify text item delimiters. This allows you to say make the delimiter a fullstop hence giving the ability to pick up sentences.
• 7Edit does not support the full Text Suite, this could be done.
• Tidying up more of the older code.
The way we have implemented the scripting ability in 7Edit is not necessarily the best way. This example is here to give you an idea of what is needed to write a scriptable application. There are bound to be better ways, or ways that are more suited to your application.
